<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Flash app &#183; GFN InSight documentation</title>
    <meta name="description" content="">
    <meta name="author" content="">

    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
    <!--[if lt IE 9]>
      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->

    <!-- Le styles -->
    <link href="bootstrap.min.css" rel="stylesheet">
    <link href="style.css" rel="stylesheet">
    <style type="text/css">
      /* Override some defaults */
      html, body {
        background-color: #eee;
      }
      body {
        padding-top: 40px; /* 40px to make the container go all the way to the bottom of the topbar */
      }
      .container > footer p {
        text-align: center; /* center align it with the container */
      }
      .container {
        width: 820px; /* downsize our container to make the content feel a bit tighter and more cohesive. NOTE: this removes two full columns from the grid, meaning you only go to 14 columns and not 16. */
      }

      /* The white background content wrapper */
      .container > .content {
        background-color: #fff;
        padding: 20px;
        margin: 0 -20px; /* negative indent the amount of the padding to maintain the grid system */
        -webkit-border-radius: 0 0 6px 6px;
           -moz-border-radius: 0 0 6px 6px;
                border-radius: 0 0 6px 6px;
        -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
           -moz-box-shadow: 0 1px 2px rgba(0,0,0,.15);
                box-shadow: 0 1px 2px rgba(0,0,0,.15);
      }

      /* Page header tweaks */
      .page-header {
        background-color: #f5f5f5;
        padding: 20px 20px 10px;
        margin: -20px -20px 20px;
      }

      /* Styles you shouldn't keep as they are for displaying this base example only */
      .content .span10,
      .content .span4 {
        min-height: 500px;
      }
      /* Give a quick and non-cross-browser friendly divider */
      .content .span4 {
        margin-left: 0;
        padding-left: 19px;
        border-left: 1px solid #eee;
      }

      .topbar .btn {
        border: 0;
      }

    </style>

    <!-- Le fav and touch icons -->
    <link rel="shortcut icon" href="images/favicon.ico">
    <link rel="apple-touch-icon" href="images/apple-touch-icon.png">
    <link rel="apple-touch-icon" sizes="72x72" href="images/apple-touch-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="114x114" href="images/apple-touch-icon-114x114.png">
  </head>

  <body>

<div class="topbar">
      <div class="fill">
        <div class="container">
          <a class="brand" href="http://stormy-stone-6022.heroku.com">GFN InSight</a>
          <ul class="nav">
	    <li><a href="index.html">Home</a></li>
            <li><a href="datastore.html">MongoDB datastore</a></li>
            <li class="active"><a href="#">Flash app</a></li>
            <li><a href="roradmin.html">RoR Admin</a></li>
          </ul>
        </div>
      </div>
    </div>


    <div class="container">

      <div class="content">
        <div class="page-header">
          <h1>Flash App <small>Built in Flash/Flex/ActionScript using Flash Builder and hosted on Heroku</small></h1>
        </div>
        <div class="row">
          <div class="span10">
            <h2>Overview</h2>
            The Flash application is the flagship application that highlights and demonstrates use of GFN's data to create visualizations for the front-end users.
            A conscious decision has been made to choose Flash over an HTML/JavaScript or HTML5/JavaScript application for reasons of cross-browser cross-platform compatibility in 2011, along with consistency in visual experience (given the intended aim to create an interactive visual experience).<p/>
            
            The application makes requests to the MongoDB datastore for specific information about specific countries, and interprets the data, in order to serve meaningful datasets for display in visualizations. The process used by the application is explained below.
            <h2>Application structure</h2>
            The structure of this application is very similar to most other Flex applications, with a few core ActionScript classes. The various distinct kinds of files are as follows:
            <ul>
            	<li><strong>MXML files</strong>: These are traditional Flex files which include XML descriptions of the layout/design of these applications, but also implement ActionScript methods for simple front-end functionality.</li>
            	<li><strong>Assets</strong>: All the images used in the application, along with style descriptor files, and other media consitutes the asset collection in the application</li>
            	<li><strong>ActionScript Classes</strong>: The controller files, such as the DataFactory for communicating to the datastore and consequently preparing the models, and the model classes themselves constitute this category</li>
            	<li><strong>Libraries</strong>: At the present stage, the only library package in the application is that of <a href="https://github.com/mikechambers/as3corelib" target="_blank" >JSON manipulation</a></li>
            </ul>
            The process on how these different components work with each other is described below in the 'Process' section.
            <h3>Process</h3>
            Find below the steps of the process from communicating to the datastore to presenting appealing visualizations to the user here:<p/>
            <ol>
            	<li>Because this application is most heavily dependant on real data to perform any operations, the application first runs the preInit() method, prior to initialization of the application. This is the method that is primarily responsible
            		for making a request to the datastore to obtain the outputs of its <a href="datastore.html">several collections</a>.</li>
            	<li>The preInit() method creates several DataFactory objects - a unique object for every combination of collection and country identifier. For each DataFactory object created, a HTTP request process in instantiated to for each collection in order to obtain the JSON data by passing in the unique URL for the location of the collection.</li>
            	<li>Upon successful return of JSON responses, a result handler decodes the JSON, and extracts the values from all the keys of the objects in the collection, based on the custom nature of each collection.</li>
            	<li>These extracted values then form the arguments for initializers to new instances of objects of different model classes (details below)</li>
            	<li>Once a new runtime object has been created for each collection read into the application, these instance objects are placed in a universal hash map (string &rarr; object) for the application, known in Flash terminology as a <strong>Dictionary</strong>.</li>
            	<li>In order to use these raw objects of data on specific collection into feeding meaningful information into visualizations, <strong>dataProvider</strong> methods are created throughout the MXML file. These methods read the raw collection objects from the Dictionary, and based on their custom needs, adopt algorithms to sort, filter and manipulate the data to return visualization-friedly Array objects that can be fed directly into the charts or graphs.</li>
            	<li>The visualizations, as defined in MXML standard, now adopt the dataProvider methods' returned array objects as <code>dataProviders</code> for themselves</li>
            </ol>
            <a name="models"></a><h3>Models</h3>
            Much of the data preparation from raw JSON decoded string into real objects that correspond to the architecture of data on GFN's MS Excel spreadsheets are done by the models of this application.
            Apart from merely redefining the schema of the database collections, they also create <a href="datastore.html#compacting" >previously compacted data from the datastore</a> ready for use by the application, removing any ambiguity for functions in the MXML file.<p/>
            Here is a list of all the models implemented in this application:
            <ul class="big-lines">
            	<li><span class="label important bigger no-transform">NFA</span> <small class="not-that-small">National Footprint Account; country-specific</small></li>
            	<li><span class="label important bigger no-transform">FD</span> <small class="not-that-small">Final Demand; country-specific</small></li>
            	<li><span class="label important bigger no-transform">EF</span> <small class="not-that-small">Ecological Footprint; country-specific</small></li>
            	<li><span class="label important bigger no-transform">CoLUM</span> <small class="not-that-small">Consumption Land Use Matrix; country-specific</small></li>
            	<li><span class="label important bigger no-transform">EI</span> <small class="not-that-small">Exports Imports; country-specific</small></li>
            	<li><span class="label important bigger no-transform">Countries</span> <small class="not-that-small">Countries; only 1 instance</small></li>
            </ul>
            All the models have only a single default constructor, which is accessed by the DataFactory methods.
            <h2>Modifying the application</h2>
            In order to modify the current sample demo application, you will need to obtain the source code of for the project,
            and then install the necessary tools on your development machine to run the program.
            <h3>Obtaining the source</h3>
            The latest version of the source code, as worked on by the team, is available in the <span class="label notice no-transform">SVN</span> repository of the Google Code project:<p/>
            <a href="http://code.google.com/p/i475-gfnsters-client/" target="_blank">http://code.google.com/p/i475-gfnsters-client/</a><p/>
            This code can be checked out publicly using the following command from terminal:
            <p/><code>svn checkout http://i475-gfnsters-client.googlecode.com/svn/trunk/ i475-gfnsters-client-read-only
</code>
			<p/>or using a GUI SVN client such as <a href="http://tortoisesvn.net/" target="_blank">Tortoise SVN</a>.
            <h3>Installing the tools</h3>
            <img src="flash-builder.png" class="img_thumb"/>It is recommended to do all Flash/Flex development using <a href="http://www.adobe.com/products/flash-builder.html" target="_blank">Flash Builder</a>. This is NOT A FREE PRODUCT offering by Adobe. However, it is free to try out in Trial mode for 60 days. Also, for students, there is an option to request for a FREE license, which in most cases is granted in a 2 weeks time.</p>
            <img src="flash.png" class="img_thumb"/>Apart from Flash Builder, it is highly recommended that you install the <a href="http://www.adobe.com/support/flashplayer/downloads.html" target="_blank">Adobe Flash Debugger plugin</a> for your specific browser needs, in order to be able to run the Debugger tool on Flash builder. This tool in essential to be able to do any minimal tracing of the runtime errors in an application.<p/>
            Upon installation of these applications, you have to import the project files into the application. You can either import the .fxp (Flash Exported Project) files, or directly open the directory with project files - based on how the exported files are stored in the repository.
            <h2>External Documentation</h2>
			<ul>
				<li><a href="http://www.connectedpixel.com/blog/scrollingcharts" target="_blank">Creating scrolling charts</a></li>
				<li><a href="http://demo.quietlyscheming.com/ChartSampler/app.html" target="_blank">Demos of visualization possibilities with Flex's internal visualization capabilities</a></li>
				<li><a href="http://demo.quietlyscheming.com/drillDown/app.html" target="_blank">Drilling down into bar charts / pie charts</a></li>
				<li><a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/rpc/http/mxml/HTTPService.html" target="_blank">Flash HTTPService documentation</a></li>
				<li><a href="http://blog.flexdevelopers.com/2009/03/flex-basics-arraycollection.html" target="_blank">Basics of ArrayCollections</a></li>
				<li><a href="http://blog.flexexamples.com/" target="_blank">Blog on Flex examples</a></li>
				<li><a href="http://www.mikechambers.com/blog/2006/03/28/tutorial-using-json-with-flex-2-and-actionscript-3/" target="_blank">JSON with ActionScript tutorial (outdated)</a></li>
				<li><a href="http://www.adobe.com/devnet/flex/articles/data_visualization.html" target="_blank">Webinar on visualizing data using Flex, by Adobe</a></li>
				<li><a href="http://sixrevisions.com/flashactionscript/10-useful-flash-components-for-graphing-data/" target="_blank">Six Revisions' recommendations for using Flash components for graphing</a></li>
			
			</ul>
			</div>
          <div class="span4">
          	<h3>Current status</h3>
          	The proposed Flash application has been stripped down to that of a 'Country profile', rather than a worldwide view. This has been done to tackle with project scope and concentrate efforts, along with being able to naturally integrate into the current GFN website.<p/>
          	There is tremendous opportunity for extensibility of this application in the future.  
          	<h3>Open Challenges</h3>
          	<ul>
          		<li>One of the biggest challenges is the cross-domain security challenges of not being allowed to make asynchronous requests to the database service on another domain (MongoLab), from the Heroku domain. Until MongoLab fixes this problem from their end or until this application along with it's services are moved to a private server on the a single domain, there is a workaround adopted.
          			The workaround currently adopted is to place the static output of the JSON files onto the server/domain the application resides on.<p/>
          			This problem does not exist when doing development from your local machine, but rather crops up only when placed on a web server.</li>
          		<li>The naming scheme of variables in the application has been poorly written - assuming that the only country that is being dealt with is China. It hasn't been designed to adopt to any country based on a parameter passed via the browser.</li>
          	</ul>
          	<h3>Software versions</h3>
          	Here is the list of the current software/driver versions in use, with no conclusions or suggestions on which versions work better than the others:
          	<ul>
          		<li>Flash: 11.0</li>
          		<li>Flash Builder: 4.5</li>
          	</ul>
            <h3>Additional notes</h3>
		If you need to manage the SVN repository, you need admin privileges as an owner/collaborator of the project <a href="http://code.google.com/p/i475-gfnsters-client/" target="_blank">i475-gfnsters-client</a> on Google Code. In order to access this data collection store, you need to be an owner/collaborator of the project stormy-stone-6022 on Heroku. <p/>
		If you are not the current owner of either of these projects on their respective services, kindly discuss this with the administrator of this application, Kyle Gracey.
          </div>
        </div>
      </div>

      <footer>
        <p>&copy; Team GFN InSight &#183; Department of Information Systems, Carnegie Mellon University</p>
      </footer>

    </div> <!-- /container -->

  </body>
</html>
